/*
 * 人员权限 - 人员权限定义
 * 
 * 主要功能：
 * - 定义人员相关的权限
 * - 提供权限管理功能
 * - 演示权限系统的使用
 * - 支持权限控制
 */

using OrchardCore.Security.Permissions;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

namespace Lombiq.TrainingDemo.Permissions;

/// <summary>
/// 人员权限 - 定义人员相关的权限
/// 
/// 主要用途：
/// - 定义人员相关的权限
 //* - 提供权限管理功能
 //* - 演示权限系统的使用
 //* - 支持权限控制
 //* 
 //* 使用场景：
/// - 控制人员管理的访问权限
/// - 管理用户对人员数据的操作权限
/// - 支持细粒度的权限控制
/// - 提供安全的人员管理
/// 
/// 设计原因：
/// - 为人员管理提供权限控制
/// - 实现安全的人员管理
/// - 支持用户权限管理
/// - 提供可扩展的权限系统
/// 
/// 设计模式：
/// - 权限模式：实现IPermissionProvider接口
/// - 提供程序模式：提供权限定义
/// - 分组模式：使用权限组组织权限
/// - 描述模式：提供权限描述信息
/// </summary>
// 权限提供程序中定义了用于授权用户并可以添加到不同角色的权限。
public sealed class PersonPermissions : IPermissionProvider
{
    /// <summary>
    /// 管理人员权限 - 允许管理所有人员数据
    /// 
    /// 功能说明：
    /// - 允许用户管理所有人员数据
    /// - 包括创建、编辑、删除人员
    /// - 提供完整的人员管理权限
    /// - 支持人员数据的全面控制
    /// 
    /// 使用场景：
    /// - 管理员管理所有人员
    /// - 人力资源部门管理员工
    /// - 系统管理员维护人员数据
    /// - 提供完整的人员管理功能
    /// </summary>
    // 定义您想要添加到仪表板上角色的权限（可以是多个）（或从这里作为默认值）。
    // 在PermissionProvider中，将权限定义为公开可访问是一个好主意，这样您就可以像之前检查EditContent权限一样引用它们。
    public static readonly Permission ManagePersons = new(
        nameof(ManagePersons),
        "管理人员内容项");

    /// <summary>
    /// 访问人员列表仪表板权限 - 允许访问人员列表仪表板
    /// 
    /// 功能说明：
    /// - 允许用户访问人员列表仪表板
    /// - 提供查看人员列表的权限
    /// - 支持人员数据的查看功能
    /// - 限制对人员数据的操作权限
    /// 
    /// 使用场景：
    /// - 查看人员列表
    /// - 访问人员仪表板
    /// - 浏览人员信息
    /// - 提供只读的人员数据访问
    /// </summary>
    // 这是另一个具有第三个参数"ImpliedBy"的权限。这意味着拥有ManagePersons权限的每个人也自动拥有AccessPersonListDashboard权限。
    // 请注意，因此AccessPersonListDashboard应该在ManagePersons之后编写。
    public static readonly Permission AccessPersonListDashboard = new(
        nameof(AccessPersonListDashboard),
        "访问人员列表仪表板",
        [ManagePersons]);

    /// <summary>
    /// 获取权限列表 - 获取所有人员相关权限
    /// 
    /// 功能说明：
    /// - 返回所有人员相关的权限
    /// - 提供权限的完整列表
    /// - 支持权限管理系统
    /// - 便于权限的注册和管理
    /// 
    /// 权限列表：
    /// - ManagePersons：管理人员权限
    /// - AccessPersonListDashboard：访问人员列表仪表板权限
    /// 
    /// 使用场景：
    /// - 权限系统注册
    /// - 权限管理界面
    /// - 权限验证
    /// - 权限分配
    /// </summary>
    /// <returns>权限列表</returns>
    public Task<IEnumerable<Permission>> GetPermissionsAsync() =>
        Task.FromResult(new[]
        {
            ManagePersons,
            AccessPersonListDashboard,
        }
        .AsEnumerable());

    /// <summary>
    /// 获取默认角色分配 - 获取权限的默认角色分配
    /// 
    /// 功能说明：
    /// - 定义权限的默认角色分配
    /// - 提供权限的初始配置
    /// - 支持角色的权限继承
    /// - 便于权限的初始设置
    /// 
    /// 角色分配：
    /// - Administrator：管理员角色，拥有所有权限
    /// - Editor：编辑者角色，拥有访问权限
    /// 
    /// 使用场景：
    /// - 系统初始化
    /// - 角色权限设置
    /// - 权限继承配置
    /// - 默认权限分配
    /// </summary>
    /// <returns>默认角色分配</returns>
    public IEnumerable<PermissionStereotype> GetDefaultStereotypes() =>
        // 提供一些默认值：哪些角色应该拥有哪些权限。
        [
            new PermissionStereotype
            {
                // 管理员默认拥有所有权限。
                Name = "Administrator",
                // 由于AccessPersonListDashboard由EditPersonList暗示，我们不必在这里列出前者。
                Permissions = [ManagePersons],
            },
            new PermissionStereotype
            {
                Name = "Editor",
                Permissions = [AccessPersonListDashboard],
            },
        ];
}

// 下一站：回到AuthorizationController并找到CanManagePersons操作。
